✨ Support upstream hcloud-ccm. ProviderID changes to `hrobot://NNNNN` #1703

guettli · 2025-11-03T14:59:10Z

This PR adds support for the upstream hcloud CCM (https://github.com/hetznercloud/hcloud-cloud-controller-manager/).

Until now, CAPH relied on our Syself fork, the "hetzner" CCM (https://github.com/syself/hetzner-cloud-controller-manager/).

The fork was required several years ago because the upstream CCM did not support bare-metal servers. Hetzner has integrated our bare metal support into its CCM (hcloud ccm PR 561), so now is the time to gradually phase out our fork.

The CCM is responsible for setting the ProviderID on Nodes. Our fork used the format hcloud://bm-NNNN for bare-metal nodes, while the upstream CCM uses hrobot://NNNN.

This PR makes both formats work, so you can use either the Syself CCM or the upstream hcloud CCM from hetznercloud.

If you use caph containing this PR, then it is safe to switch to the upstream ccm. Existing nodes will keep their legacy hcloud://bm-NNNN ProviderIDs. Only new nodes will get hrobot://NNNN. The upstream ccm can read the legacy format.

HCloud nodes are not affected by this change.

Changes

More docs for HetznerBareMetalMachineSpec.ProviderID
Create HetznerBareMetalMachineSpec.ProviderID in the new format: hrobot://NNNN. Before it was hcloud://bm-NNNN.
Validate that the Provider does not get changed (ValidationWebHook)
More docs for HetznerCluster.Spec.HetznerSecret.Name
To ensure compatibilty with both CCMs: If HetznerCluster.Spec.HetznerSecret.Name is not "hcloud", then create two secrets in the wl-cluster. One with name "hcloud", one with the name of HetznerCluster.Spec.HetznerSecret.Name. This ensures compatibility with upstream hcloud-ccm.
To ensure compatibilty with both CCMs: hcloud-ccm wants the HCLOUD_TOKEN to be on key "token" in the secret. Syself ccm expects the key to be "hcloud". Create both keys, so that both CCMs are supported.
Added an entry note to the secret in the wl-cluster. This helps new users to understand that this secret gets reconciled by caph.
Changed defaults in HetznerSecretKeyRef from "hcloud-token", "hetzner-robot-user", "hetzner-robot-password" to "token", "robot-user", "robot-password". This aligns to the upstream ccm values.
update CSR-Controller to support both: the legacy ProviderID (hcloud://bm-NNNN) and the new ProviderID (hrobot://NNNN)
renamed internal function reconcileTargetSecret to reconcileWorkloadClusterSecrets and rename some internal variables to make differentiation between mgt-cluster and wl-cluster more obvious.
Check that HCloud ProviderID starts with "hcloud"
... TODO

TODO Release as caph v1.1.0

This changes a lot, additionally the last caph release was not done from main. This should be released as v1.1.0

This version get used already used in the docs. Please adapt, if a different version will contain that PR.

Co-authored-by: guettli <[email protected]>

…nding.

janiskemper · 2025-11-04T20:56:37Z

controllers/hetznercluster_controller.go

+
+		// upstream hcloud-ccm uses the secret key "token", while the old Syself ccm used "hcloud".
+		// For compatibilty, we create always the other key, too.
+		for _, key := range []string{"token", "hcloud"} {


right now we create a duplicate right? Wouldn't it be enough to create the right key (e.g. "token" for the upstream ccm)?

The result should work for both CCMs.

By creating both keys we are safe. Users can try to upstream hcloud-ccm. If it fails, they can easily switch back to the old syself-ccm.

Why not create both keys?

you create both keys in both secrets. But you actually need only one key per secret right?

IMO it is less confusing for users if we have only the correct key in the secret. That's why I would implement it in that way

Suggestion: We deprecate HetznerCluster.Spec.HetznerSecret.Key.HCloudToken. In the docstring we explain that the controller will currently create "token", "hcloud" and the specified value.

In the long run (maybe caph version released at the end of 2027) we will remove that field and will only create "token".

I think it is perfectly fine if that value can't be configured.

What do you think about that?

I suppose so. Can you discuss this with @batistein?

@janiskemper I talked to Sven. He is fine with creating three keys in the secret. But he does not want to deprecate this setting.

okay can you then update the comments in the function to make that clear that these three keys are created for the hcloud token?
EDIT: And this should be also documented I suppose

@janiskemper I added a comment to the function and to the related field in the struct:

623f05a

ok now?

controllers/hetznercluster_controller.go

pkg/services/baremetal/baremetal/baremetal.go

…d-format-of-upstream-ccm

janiskemper · 2025-11-21T14:41:36Z

api/v1beta1/types.go

 type HetznerSecretKeyRef struct {
-	// HCloudToken defines the name of the key where the token for the Hetzner Cloud API is stored.
-	// We recommend to use "token", because this is the default of upstream hcloud-ccm.
+	// hcloudToken defines the name of the key where the token for the Hetzner Cloud API is stored.


capital "HCloudToken"

janiskemper · 2025-11-21T14:41:53Z

api/v1beta1/types.go

-	// We recommend to use "token", because this is the default of upstream hcloud-ccm.
+	// hcloudToken defines the name of the key where the token for the Hetzner Cloud API is stored.
+	// We recommend to use "token", because this is the default of upstream hcloud-ccm, while the
+	// legacy Syself ccm uses "hcloud". For maximal compatibility up to three keys get created in the


let's write "Syself fork" instead of "Syself ccm"

✨ Support upstream hcloud-ccm. ProviderID changes to hrobot://NNNN

a958fc0

Copilot AI mentioned this pull request Nov 3, 2025

Fix spelling and grammar in PR #1703 comments #1704

Closed

... make generate.

9e0dd80

github-actions bot added size/M Denotes a PR that changes 50-200 lines, ignoring generated files. area/code Changes made in the code directory area/api Changes made in the api directory labels Nov 3, 2025

Copilot AI added a commit that referenced this pull request Nov 3, 2025

Fix typos and grammar in PR #1703: alligns->aligns, add missing 'to'

75a4370

Co-authored-by: guettli <[email protected]>

guettli mentioned this pull request Nov 3, 2025

🌱 Support hrobot:// ProviderID of upstream ccm. syself/hetzner-cloud-controller-manager#72

Open

fix grammar.

42e9483

github-actions bot added size/S Denotes a PR that changes 20-50 lines, ignoring generated files. and removed size/M Denotes a PR that changes 50-200 lines, ignoring generated files. labels Nov 3, 2025

guettli added 2 commits November 4, 2025 12:25

ProviderID of infra machines should not change: Validate that.

619dc53

make generate.

88de8f0

github-actions bot added size/M Denotes a PR that changes 50-200 lines, ignoring generated files. and removed size/S Denotes a PR that changes 20-50 lines, ignoring generated files. labels Nov 4, 2025

guettli added 6 commits November 4, 2025 17:22

added docs, rename vars for better mgt-cluster vs wl-cluster understa…

2185a46

…nding.

create both keys in the secret: hcloud and token.

1f6ea11

add note about source of secret.

09a030a

create both secrets for compatibilty.

990a5b5

added a comment to hcloud change.

0e3c069

wording.

dec7bfe

guettli requested a review from janiskemper November 4, 2025 16:51

github-actions bot added size/L Denotes a PR that changes 200-800 lines, ignoring generated files. area/hack Changes made in the hack directory and removed size/M Denotes a PR that changes 50-200 lines, ignoring generated files. labels Nov 4, 2025

janiskemper reviewed Nov 4, 2025

View reviewed changes

inlined creation of ProviderID, to reduce complexity.

b375950

guettli requested a review from janiskemper November 5, 2025 09:28

guettli added 2 commits November 5, 2025 10:28

Merge remote-tracking branch 'origin/main' into tg/support-provider-i…

5f62c63

…d-format-of-upstream-ccm

fix typos.

40d4fe9

guettli added 4 commits November 5, 2025 12:26

make geneate.

1fd26b9

updated comment about "token"

cdca0c3

be explicit: recommend the defaults of upstream hcloud-ccm.

4aea658

make makefile target install-ccm-in-wl-cluster work again.

a6979e0

guettli mentioned this pull request Nov 5, 2025

📖 Compare our fork with upstream. syself/hetzner-cloud-controller-manager#73

Merged

Merge branch 'main' into tg/support-provider-id-format-of-upstream-ccm

3268799

guettli requested a review from batistein November 11, 2025 10:11

guettli added 3 commits November 13, 2025 13:53

Merge remote-tracking branch 'origin/main' into tg/support-provider-i…

343c68d

…d-format-of-upstream-ccm

added comment: we create up to three times the HLCOUD_KEY in the secret.

623f05a

generate-manifests.

c28ffdf

janiskemper reviewed Nov 21, 2025

View reviewed changes

✨ Support upstream hcloud-ccm. ProviderID changes to hrobot://NNNNN #1703

Are you sure you want to change the base?

✨ Support upstream hcloud-ccm. ProviderID changes to hrobot://NNNNN #1703

Uh oh!

Conversation

guettli commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

TODO Release as caph v1.1.0

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janiskemper Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

✨ Support upstream hcloud-ccm. ProviderID changes to `hrobot://NNNNN` #1703

✨ Support upstream hcloud-ccm. ProviderID changes to `hrobot://NNNNN` #1703

guettli commented Nov 3, 2025 •

edited

Loading

janiskemper Nov 13, 2025 •

edited

Loading